{% extends "../docshell.html" %}
{% block title %}Google Spreadsheets{% endblock %}
{% block navigation %}{% include 'navigation.html' %}{% endblock %}
{% block content %}
<h1>Use with Google Spreadsheets</h1>
<p>
  This page describes how you can use Rhizosphere withing a
  <a href="http://docs.google.com">Google Spreadsheet</a>.
</p>

<h2>Contents</h2>
<ul class="page_toc">
  <li><a href="#basic">Basic Usage</a></li>
  <li><a href="#fullscreen">Fullscreen mode</a></li>
  <li><a href="#advanced">Advanced Gadget Options</a></li>
  <li><a href="#categories">Handling categories</a></li>
  <li><a href="#hierarchical">Handling hierarchical data</a></li>
</ul>

<a name="basic"><h2>Basic Usage</h2></a>
<p>
  First, login to <a href="http://docs.google.com">docs.google.com</a> and
  create a new spreadsheet. Start entering some data or import them from an
  external source, until you're satisfied with the contents.
  For example, here is the
  <a href="https://spreadsheets0.google.com/ccc?key=tfsbXD2LYRhYmC_SRKSreXA&hl=en_GB#gid=0">
    spreadsheet I created</a> to decided which mobile phone is right for me.
  You can access it live, and copy it for your experiments.
</p>
<p>
  You should organize your data according to these rules:
</p>
<ul>
  <li>Every <strong>row</strong> should represent an item to be displayed,</li>
  <li>Every <strong>column</strong> should represent an attribute or
    characteristic your items have.
  </li>
</ul>
<img src="/static/doc/img/spreadsheet_0.png"
     class="screenshot" style="border: 1px solid #bbb">

<p>Select a range of cells. Then from the toolbar, choose
  <strong>Insert &gt; Gadget</strong>. Choose to insert a
  <strong>custom</strong> gadget and type in this URL:
</p>
<pre>
  http://www.rhizospherejs.com/ig
</pre>
<p>
  Click the Add button. This will add the Rhizosphere gadget on your
  spreadsheet and open its configuration page, as shown here:
</p>
<img src="/static/doc/img/gadgetinfo.png"
     class="screenshot" style="border: 1px solid #bbb">
<p>
  Verify that the <strong>Range</strong> option matches the cells you want to analyze,
  or adjust it accordingly. That's it!
</p>
<img src="/static/doc/img/spreadsheet_1.png"
     class="screenshot" style="border: 1px solid #bbb">
<p>
  Try using the menus in the bottom bar to change the items layout and filter
  them. You can also drag them around, select them (just click them) and
  restrict your work on the selected items only.
</p>
<p>
  If you choose the <strong>Autoanalyze data</strong> checkbox within the gadget
  options, Rhizosphere will do its best to extract new dimensions out of your
  data. In the above example it's using colors and sizes to display
  differences in prices and weights of the phones. A legend is provided
  if you feel confused.
</p>

<a name="fullscreen"><h2>Fullscreen mode</h2></a>
<p>
  Rhizosphere can operate in different modes depending on how much space it has
  to render its contents. So far Rhizosphere has been constrained to a
  gadget-size rendering.
</p>
<p>
  Withing Google Spreadsheets you can move Rhizosphere to his own sheet (from
  the gadget options, choose <strong>Move to own sheet...</strong>). Rhizosphere
  will then render itself using the full-page user interface, which you have
  already seen in the <a href="/doc/users_overview.html">Using Rhizosphere</a> section.
</p>

<a name="advanced"><h2>Advanced Gadget options</h2></a>
<p>
  When Rhizosphere is embedded inside a spreadsheet as a gadget, you have
  access to a set of advanced options.
</p>
<p>
  Choose the <strong>Edit Gadget...</strong> link from within the gadget menu,
  and you will have access to a set of advanced configuration options:
</p>
<dl>
  <dt>Range / Datasource URL</dt>
  <dd>The range of cells (if inside a Google Spreadsheet) or the datasource
    (if inside another gadget container like iGoogle) that Rhizosphere uses to
    extract the data to visualize.</dd>
  <dt>Fancy Animations</dt>
  <dd>
    Animates transitions, layouts and filtering. Disable this if you experience
    slowness or you are working with many ( hundreds ) elements.
    You can usually keep this on with any worries.
  </dd>
  <dt>
    Autoanalyze data
  </dt>
  <dd>
    Rhizosphere will try to understand the type of your data and modify the
    display accordingly. It will use the first column as the label for every
    item, and map the first two numeric columns to the color and size of each
    element. You can override this defaults by using the options labeled
    as Advanced.
  </dd>
  <dt>
    When Fullscreen, show
  </dt>
  <dd>
    When in fullscreen mode, Rhizosphere will display more fields for each item,
    rather than the label only. Here you can specify how many fields you want
    to see.
  </dd>
  <dt>
    Advanced, as Label use
  </dt>
  <dd>
    Explicitly specify the column ( either by typing its label or its
    identifying letter ) that Rhizosphere will use as label for each item.
  </dd>
  <dt>
    Advanced, as Size use
  </dt>
  <dd>
    Explicitly specify the column ( either by typing its label or its
    identifying letter ) that Rhizosphere will use as the Size for each item.
    The column should contain a numeric value. Bigger numbers will result in
    bigger sizes.
  </dd>
  <dt>
    Advanced, as Color use
  </dt>
  <dd>
    Explicitly specify the column ( either by typing its label or its
    identifying letter ) that Rhizosphere will use as the Color for each item.
    The column should contain a numeric value. Rhizosphere will use a color
    palette where bigger numbers will result in darker shades of the palette
    color.
  </dd>
</dl>

<a name="categories"><h2>Handling categories</h2></a>
<p>
  Google Spreadsheets do not have an explicit way to declare that the values in
  a given text column belong to a finite set of categories rather than being
  free text. Without additional configuration, Rhizosphere will configure
  filters over text columns as simple input fields where you can type in strings
  that will be matched against the column values.
</p>
<p>
  You can instruct Rhizosphere to use dropdown selection boxes by adding the
  tag word <code>CAT</code> (uppercase) to the column header.
</p>
<p>
  Do you want a selection box that allow multiple choices? Use the word
  <code>CATMUL</code> instead.
</p>
<img src="/static/doc/img/gadgetcat.png"
  class="screenshot" style="border: 1px solid #bbb">

<a name="hierarchical"><h2>Handling hierarchical data</h2></a>
<p>
  Google Spreadsheets lets you organize data in tabular fashion, but does not
  have an explicit way to describe hierarchical data. Hierarchical relationships
  appear naturally in several domains, such as when trying to visualize
  organizational charts, or grouping geographic data at different depths
  (country, region, city and such).
</p>
<p>
  Rhizosphere contains several features that leverage hierarchical relationships
  found in your data, such as tree and
  <a href="http://en.wikipedia.org/wiki/Treemapping">treemap</a> layouts.
</p>
<p>
  If you want Rhizosphere to infer a hierarchical structure from your Google
  Spreadsheet data, use any of the following conventions.
</p>
<h4>Describe parent-child relationships</h4>
<p>
  Define two adjacent columns, the first containing an identifier of the
  datapoint the row represents (such as the name of the employee, in the
  organizational chart scenario), the second containing an identifier of the
  parent datapoint (such as the employee manager). If a record has no parent,
  leave the value of the second column empty.
</p>
<p>
  Make sure the label of the column containing the parent data follows this
  naming rule: <strong><code>Parent</code> + label of the preceding
  column</strong>. For example, in the organizational chart case, the first
  column might have the "Employee" label, and the second column will have the
  "ParentEmployee" label.
</p>
<p>
  Rhizosphere will automatically pick up the relationship between the two
  columns and will let you display the data using either trees or treemaps.
</p>
<img src="/static/doc/img/hierarchical_1.png" class="screenshot">

<h4>Describe tree branches using multiple columns</h4>
<p>
  Alternatively, you can define hierarchical data by fully describing the branch
  of the tree each spreadsheet row belongs to. Define as many adjacent
  columns as the depth of the tree you want to represent. Make sure all the
  colums <strong>have the same label</strong>. Then, for every row, fill
  the columns with node values running from the tree root down to the
  element the row itself represents (or belongs to).
</p>
<p>
  Again, Rhizosphere will automatically rebuild the tree structure for you.
</p>
<img src="/static/doc/img/hierarchical_2.png" class="screenshot">

<h4>Describe tree branches using a single comma-separated column</h4>
<p>
  Finally, you can also put all your hierarchical information in a single
  column. Fill the columns with node values running from the tree root down
  to the element the row itself represents (or belongs to), separating them
  with commas. If you do so, <strong>add the <code>CATHIE</code> word tag to the
  column label</strong>. Rhizosphere will notice the column label and try to
  rebuild the tree from the column values.
</p>
<img src="/static/doc/img/hierarchical_3.png" class="screenshot">

<h4>Multiple hierarchies</h4>
<p>
  You are not limited to having a single hierarchy in your data. Rhizosphere can
  handle as many as you want. Here you can find a slightly more complex example
  that list employees of a fictional store arranging them both according to
  their organizational chart and according to the department they work in.
</p>
<p>
  The two included Rhizosphere visualizations display the organizational chart
  and a treemap of sales data arranged by department. You can find the
  original spreadsheet
  <a href="https://spreadsheets.google.com/ccc?hl=en_GB&key=tjCJjlcgOV8jMGnptI2OeNQ&hl=en_GB#gid=0">
    here</a>.
</p>
<img src="/static/doc/img/hierarchical_4.png" class="screenshot">

{% endblock %}